home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 432_01 / ptmid3 / mod-form.txt < prev    next >
Text File  |  1994-04-17  |  20KB  |  392 lines
  1. Noisetracker/Soundtracker/Protracker Module Format
  2. --------------------------------------------------
  3. Credits:  Lars Hamre, Norman Lin, Kurt Kennett, Mark Cox, Peter Hanning,
  4.           Steinar Midtskogen, Marc Espie, and Thomas Meyer
  5. (All numbers below are given in decimal)
  6.           4th Revision
  7.  
  8. Module Format:
  9. # Bytes   Description
  10. -------   -----------
  11. 20        The module's title, padded with null (\0) bytes. Original
  12.           Protracker wrote letters only in uppercase.
  13.  
  14. (Data repeated for each sample 1-15 or 1-31)
  15. 22        Sample's name, padded with null bytes. If a name begins with a
  16.           '#', it is assumed not to be an instrument name, and is
  17.           probably a message.
  18. 2         Sample length in words (1 word = 2 bytes). The first word of
  19.           the sample is overwritten by the tracker, so a length of 1
  20.           still means an empty sample. See below for sample format.
  21. 1         Lowest four bits represent a signed nibble (-8..7) which is
  22.           the finetune value for the sample. Each finetune step changes
  23.           the note 1/8th of a semitone. Implemented by switching to a
  24.           different table of period-values for each finetune value.
  25. 1         Volume of sample. Legal values are 0..64. Volume is the linear
  26.           difference between sound intensities. 64 is full volume, and
  27.           the change in decibels can be calculated with 20*log10(Vol/64)
  28. 2         Start of sample repeat offset in words. Once the sample has
  29.           been played all of the way through, it will loop if the repeat
  30.           length is greater than one. It repeats by jumping to this
  31.           position in the sample and playing for the repeat length, then
  32.           jumping back to this position, and playing for the repeat
  33.           length, etc.
  34. 2         Length of sample repeat in words. Only loop if greater than 1.
  35. (End of this sample's data.. each sample uses the same format and they
  36.  are stored sequentially)
  37. N.B. All 2 byte lengths are stored with the Hi-byte first, as is usual
  38.      on the Amiga (big-endian format).
  39.  
  40. 1         Number of song positions (ie. number of patterns played
  41.           throughout the song). Legal values are 1..128.
  42. 1         Historically set to 127, but can be safely ignored.
  43.           Noisetracker uses this byte to indicate restart position -
  44.           this has been made redundant by the 'Position Jump' effect.
  45. 128       Pattern table: patterns to play in each song position (0..127)
  46.           Each byte has a legal value of 0..63 (note the Protracker
  47.           exception below). The highest value in this table is the
  48.           highest pattern stored, no patterns above this value are
  49.           stored.
  50. (4)       The four letters "M.K." These are the initials of
  51.           Unknown/D.O.C. who changed the format so it could handle 31
  52.           samples (sorry.. they were not inserted by Mahoney & Kaktus).
  53.           Startrekker puts "FLT4" or "FLT8" here to indicate the # of
  54.           channels. If there are more than 64 patterns, Protracker will
  55.           put "M!K!" here. You might also find: "4CHN", "6CHN" or "8CHN"
  56.           which indicates 4, 6 or 8 channels respectively. If no letters
  57.           are here, then this is the start of the pattern data, and only
  58.           15 samples were present.
  59.  
  60. (Data repeated for each pattern:)
  61. 1024      Pattern data for each pattern (starting at 0).
  62. (Each pattern has same format and is stored in numerical order.
  63.  See below for pattern format)
  64.  
  65. (Data repeated for each sample:)
  66. xxxxxx    The maximum size of a sample is 65535 words. Each sample is
  67.           stored as a collection of bytes (length of a sample was given
  68.           previously in the module). Each byte is a signed value (-128
  69.           ..127) which is the channel data. When a sample is played at a
  70.           pitch of C2 (see below for pitches), about 8287 bytes of
  71.           sample data are sent to the channel per second. Multiply the
  72.           rate by the twelfth root of 2 (=1.0595) for each semitone
  73.           increase in pitch eg. moving the pitch up 1 octave doubles the
  74.           rate. The data is stored in the order it is played (eg. first
  75.           byte is first byte played). The first word of the sample data
  76.           is used to hold repeat information, and will overwrite any
  77.           sample data that is there (but it is probably safer to set it
  78.           to 0).
  79.           The rate given above (8287) conveys an inaccurate picture of
  80.           the module-format - in reality it is different for different
  81.           Amigas. As the routines for playing were written to run off
  82.           certain interrupts, for different Amiga computers the rate to
  83.           send data to the channel will be different. For PAL machines
  84.           the clock rate is 7093789.2 Hz and for NTSC machines it is
  85.           7159090.5 Hz. When the clock rate is divided by twice the
  86.           period number for the pitch it will give the rate to send the
  87.           data to the channel, eg. for a PAL machine sending a note at
  88.           C2 (period 428), the rate is 7093789.2/856 ~= 8287.1369
  89. (Each sample is stored sequentially)
  90.  
  91. Pattern Format:
  92. Each pattern is divided into 64 divisions. By allocating different
  93. tempos for each pattern and spacing the notes across different amounts
  94. of divisions, different bar sizes can be accommodated.
  95.  
  96. Each division contains the data for each channel (1..4) stored after
  97. each other. Channels 1 and 4 are on the left, and channels 2 and 3 are
  98. on the right. In the case of more channels: channels 5 and 8 are on the
  99. left, and channels 6 and 7 are on the right, etc. Each channel's data in
  100. the division has an identical format which consists of 2 words (4
  101. bytes). Divisions are numbered 0..63. Each division may be divided into
  102. a number of ticks (see 'set speed' effect below).
  103.  
  104. Channel Data:
  105.                   (the four bytes of channel data in a pattern division)
  106. 7654-3210 7654-3210 7654-3210 7654-3210
  107. wwww xxxxxxxxxxxxxx yyyy zzzzzzzzzzzzzz
  108.  
  109.     wwwwyyyy (8 bits) is the sample for this channel/division
  110. xxxxxxxxxxxx (12 bits) is the sample's period (or effect parameter)
  111. zzzzzzzzzzzz (12 bits) is the effect for this channel/division
  112.  
  113. If there is to be no new sample to be played at this division on this
  114. channel, then the old sample on this channel will continue, or at least
  115. be "remembered" for any effects. If the sample is 0, then the previous
  116. sample on that channel is used. Only one sample may play on a channel at
  117. a time, so playing a new sample will cancel an old one - even if there
  118. has been no data supplied for the new sample. Though, if you are using a
  119. "silence" sample (ie. no data, only used to turn off other samples) it
  120. is polite to set its default volume to 0.
  121.  
  122. To determine what pitch the sample is to be played on, look up the
  123. period in a table, such as the one below (for finetune 0). If the period
  124. is 0, then the previous period on that channel is used. Unfortunately,
  125. some modules do not use these exact values. It is best to do a binary-
  126. search (unless you use the period as the offset of an array of notes..
  127. expensive), especially if you plan to use periods outside the "standard"
  128. range. Periods are the internal representation of the pitch, so effects
  129. that alter pitch (eg. sliding) alter the period value (see "effects"
  130. below).
  131.  
  132.           C    C#   D    D#   E    F    F#   G    G#   A    A#   B
  133. Octave 1: 856, 808, 762, 720, 678, 640, 604, 570, 538, 508, 480, 453
  134. Octave 2: 428, 404, 381, 360, 339, 320, 302, 285, 269, 254, 240, 226
  135. Octave 3: 214, 202, 190, 180, 170, 160, 151, 143, 135, 127, 120, 113
  136.  
  137. Octave 0:1712,1616,1525,1440,1357,1281,1209,1141,1077,1017, 961, 907
  138. Octave 4: 107, 101,  95,  90,  85,  80,  76,  71,  67,  64,  60,  57
  139.  
  140. Octaves 0 and 4 are NOT standard, so don't rely on every tracker being
  141. able to play them, or even not crashing if being given them - it's just
  142. nice that if you can code it, to allow them to be read.
  143.  
  144. Effects:
  145. Effects are written as groups of 4 bits, eg. 1871 = 7 * 256 + 4 * 16 +
  146. 15 = [7][4][15]. The high nibble (4 bits) usually determines the effect,
  147. but if it is [1